feat(build.mcpp): the rule-package specification, a portable check role, and modules/ for mcpp itself (2026.8.29.1) - #525

… mcpp itself

The mechanism for distributing a build rule as an ordinary package landed in
2026.8.5.1 and works. What was missing was the specification: what a rule
package may be called, what it may depend on, and where its dependencies go.
The index holds one rule package out of 132 descriptors, so every property of
the abstraction rested on a single sample.

Identity is enforced by the engine; shape is documented for authors. The split
is not a matter of taste: in the previous round exactly one rule was written as
a pure convention -- `mcpp.rules.*` as a reserved prefix -- and it is the one
rule that was silently abandoned during implementation. It was also
unimplementable from the moment it was written, since module names came from
the bare `package.name` and SPEC-001 forbids a dot there.

## `[build-dependencies]` now does something

The section has been parsed, merged across workspace members and
conditionalised by target predicate for a long time, and no code path read it
to make a decision; `types.cppm` annotated the field "host-side tools (M5+
behavior)". Writing it produced a manifest that loaded, no diagnostic, and no
effect.

The section and the per-edge request answer orthogonal questions. The section
says whether the package itself reaches the target; the request (`tools`,
`host-module`) says which build-time product is wanted. protobuf is the case
that proves they must stay separate: a project links libprotobuf and needs
protoc, written once in `[dependencies]`.

## A rule may depend on another rule

Declared in the rule's own `[build-dependencies]`. The mechanism is ordering,
not new machinery: build_program.cppm accumulates the module flags as it
compiles host modules in list order, so the caller topologically sorts the list
and each entry sees the BMIs ahead of it. BMI agreement stays structural
because the flag set does not change.

The consumer may not import what it never declared. Provisions cross one
further edge only on a `reexport = true` edge, and mcpp enforces that rather
than leaving it to the compiler -- under GCC the import would work and then
fail on someone else's machine.

Rules used to be leaves, and that was not a design choice: both live build-time
channels are written by the CONSUMER on an edge, so a rule had no way to
request anything on its own behalf.

## Fixes

A rule's own `[dependencies]` were compiled and linked into the consumer's
binary. The exclusion predicate was per-edge -- "every in-edge is a host-module
edge" -- which is right about the rule and wrong about everything behind it.
Restated as forward reachability from the target's dependency roots, which also
makes the dual-role case right without a special case: a package the project
depends on directly stays in the target even when a build-time path reaches it
too. Measured in tests/e2e/310: with the old predicate the library's symbol is
in the binary; with the new one it is not.

A rule's module name is now what its source declares. `build_host_module` binds
that name differently per compiler family -- `/reference name=ifc` on MSVC,
`-fmodule-file=name=pcm` on Clang, and nothing at all on GCC, whose BMIs are
implicit under gcm.cache and keyed by the declared name. A rule whose lib root
declared anything else built on GCC and failed on the other two. The successful
import therefore does not discriminate on Linux, so the e2e asserts on the BMI
and object filenames instead.

Two rules declaring one module name are refused, naming both packages and both
interface paths. Without the check both compiles write one object, the second
overwrites the first, and the survivor reaches the link twice as
`multiple definition of 'initializer for module X'` -- one file named twice,
one package named twice, and no mention that two packages are involved.

`mcpp.` is reserved for rules maintained by the mcpp project. A warning, not an
error: the engine cannot decide who is official, and a path dependency, a
private mirror and an internal fork are all legitimate.

## `modules/`

Six leaf modules move out of `src/` into independent packages used by path:
json, toml, log, source-kind, dyndep, version-req. Grouping mcpp's 157 modules
by directory and computing strongly connected components puts 17 of 21 groups
in one component, which reads as "cannot be split" until the back-edges are
counted: `platform` has five, four of them inside `platform/xlings/`, which is
a different layer wearing platform's name.

`modules/` holds what is linked into the binary and `src/` is what has not been
separated yet. No `apps/`: mcpp produces one binary, and a directory with one
member and no distinction behind it has to be explained every time it is read.

Adding a module means editing four files and three of those omissions fail
later and elsewhere -- the worst only on a macOS machine with no mcpp to
rebuild with. `.github/tools/check_modules_wiring.sh` holds them together, and
each of its checks was observed failing before it was trusted.

## Tests

Four e2e files and eleven unit tests, each seen failing against the previous
behaviour before being kept. Two claims in the design document were corrected
by measurement while doing so: the collision is a link error rather than a
silent success, and the divergent-name import passes on GCC.

… them

The unit under `modules/` is a SUBSYSTEM, not a file. One file per package
would turn a directory listing into nine manifests and call it architecture.

  libs             json + toml -- text-format parsers, vendored and in-house
  log              leveled diagnostics
  versioning       mcpp.version + mcpp.version_req
  source-kind      the source-file role table
  dyndep           ninja dyndep emission
  platform         the OS abstraction: fs, process, axis, shell, terminal
  manifest         mcpp.toml and the xpkg descriptor, plus the vocabulary they
                   are written in
  toolchain-model  what a toolchain IS -- triple, model, dialect, cppfly,
                   fingerprint, linkmodel
  buildmcpp        the build.mcpp CONTRACT -- program_protocol, directives,
                   provisions, tool_store

Dependencies between them are declared and enforced rather than assumed, so
`mcpp test -p <member>` builds each one ALONE and a subsystem relying on
something it does not declare fails there while compiling fine in the root.

## Three cuts, one mistake

Every group-level cycle was produced by a countable set of back-edges, and each
one was a module named for where it sat rather than for what it did.

`src/platform/xlings/` was never platform: it is the xlings integration, which
by its nature knows about packages, indexes and manifests. Its modules were
named `mcpp.platform.xlings` while their namespace already said
`mcpp::xlings`; both now agree, in `src/xlings/`.

`runtime_binding.cppm` imported the whole of `mcpp.config` to read ONE path out
of it, which put the OS layer above configuration, xlings and the package
manager. The caller passes the path; the file describes the xlings runtime
contract rather than the OS, so it moved to `src/runtime/` with its only
dependent.

`toolchain.fingerprint` imported `toolchain.detect` for a type -- `Toolchain`
-- that `toolchain.model` defines and `detect` merely re-exports. The import
named a CONSUMER of the type rather than its provider and dragged toolchain
detection behind it. That one is load-bearing: every module on the
build-program side needs `fingerprint` for `hash_file`, so while that edge
pointed at `detect` the whole build.mcpp contract sat transitively above the
package manager. One import line was the entire distance.

## What stays in src/, and why it is not a defect

`build_program.cppm` and `hostprogram.cppm` -- the half that compiles and runs
the program -- need `toolchain.registry` and `toolchain.stdmod`, which reach
into detection, the compiler families and xlings. A thing that compiles and
runs a program is a toolchain consumer by construction; moving it would
relocate the dependency rather than remove it.

## Tests at two altitudes

Each package carries its own tests, and the root keeps a suite that crosses
layers. A subsystem test going red means the contract changed; the root's
cross-check going red means the contract held and a consumer drifted.

`tests/unit/test_subsystem_contracts.cpp` is the new one: it asserts that the
protocol number the bundled module announces is SUBSTITUTED rather than spelled
(so the announced value cannot drift from the checked one), and that the
compiled binary's version equals the root manifest's.

⚠️ `mcpp test -p <member>` exits 0 for a member with no tests, so CI's loop is
green either way and "has no tests" reads exactly like "tests pass".
`check_modules_wiring.sh` prints which members have none, and does not fail on
them.

`versioning` is not called `version`: that word is a reserved key inside a
dependency specification, so `[dependencies.mcpp] version = { path = … }`
parses as the mcpp dependency's version field and fails with an error about the
wrong table.

…inking

Three things the subsystem split moved out from under checks that name paths,
all found by sweeping rather than by a failure.

`bootstrap-mcpp/action.yml` keyed target/ on `hashFiles('src/**', …)`. Half of
mcpp's sources now live under `modules/`, so editing one would restore a
target/ built from different sources and report success -- the exact failure a
cache key exists to prevent, arriving silently.

`check_narrow_conversions.sh` scanned `src/modgraph src/scaffold`. The glob
walker it was written for moved to `modules/manifest/src/glob.cppm` and left
the scope without changing what the pass printed. A scope written as directory
names shrinks silently when a file moves, so the file is now named directly and
its ABSENCE is a hard error.

`check_modules_wiring.sh` gains the cache-key check.

⚠️ Its first version passed the negative test: it asked whether the FILE
mentioned `modules/**`, and was satisfied by the comment sitting above the key
explaining why `modules/**` belongs there. A check a comment can satisfy is
checking the prose. The unit is the line.

Both new checks were seen failing before being kept -- the narrow-conversion
one by injecting a narrowing into the moved file, since it legitimately has
none today.

Also: the descriptor count in the design document was taken from
`mcpp-community/mcpp-index` while `mcpp index list` reports
`mcpplibs/mcpp-index` as the default. The right question asked of the wrong
object; the conclusion survived (one rule package either way) and the number
did not. 133, and the document now says which index.